/*******************************************************************************
 * Copyright (c) 2000, 2005 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package com.architexa.org.eclipse.gef.ui.palette;

import java.beans.PropertyChangeListener;

import org.eclipse.swt.graphics.FontData;

/**
 * <code>PaletteViewerPreferences</code> is used to store/persist the various settings of
 * a GEF palette.
 * <p>
 * <EM>IMPORTANT</EM>: This interface is <EM>not</EM> intended to be implemented by
 * clients. Clients should inherit from {@link DefaultPaletteViewerPreferences}.  New
 * methods may be added in the future.
 * 
 * @author Pratik Shah
 */
public interface PaletteViewerPreferences {

/**
 * This is a constant for one of the auto-collapse options.
 * <br>
 * Indicates that containers should always auto-collapse.
 */
int COLLAPSE_ALWAYS = 2;

/**
 * This is a constant for one of the auto-collapse options.
 * <br>
 * Indicates that containers should never auto-collapse.
 */
int COLLAPSE_NEVER = 1;

/**
 * This is a constant for one of the auto-collapse options.
 * <br>
 * Indicates that containers should auto-collapse only when there is not enough room on
 * the palette.  This is the default auto-collapse setting.
 */
int COLLAPSE_AS_NEEDED = 0;

/**
 * This is a constant for one of the layout options.
 * <br>
 * Indicates that the palette should be displayed in the columns mode.
 */
int LAYOUT_COLUMNS = 1;

/**
 * @deprecated	Use LAYOUT_COLUMNS instead.
 */
int LAYOUT_FOLDER = LAYOUT_COLUMNS;

/**
 * This is a constant for one of the layout options.
 * <br>
 * Indicates that the palette should be displayed in the list mode.
 * This is the default layout setting.
 */
int LAYOUT_LIST = 0;

/**
 * This is a constant for one of the layout options.
 * <br>
 * Indicates that the palette should be displayed in the icons only mode.
 */
int LAYOUT_ICONS = 2;

/**
 * This is a constant for one of the layout options.
 * <br>
 * Indicates that the palette should be displayed in the details mode.
 */
int LAYOUT_DETAILS   = 3;

/**
 * Property name for the layout setting.  If the PropertyChangeEvent fired
 * has this property name, it means that the layout setting was changed.
 */
String PREFERENCE_LAYOUT = "Layout Setting"; //$NON-NLS-1$

/**
 * Property name for the auto-collapse setting.  If the PropertyChangeEvent 
 * fired has this property name, it means that the auto-collapse setting 
 * was changed.
 */
String PREFERENCE_AUTO_COLLAPSE = "Auto-Collapse Setting"; //$NON-NLS-1$

/**
 * Property name for the large icon setting for columns layout.  If the PropertyChangeEvent
 * fired has this property name, it means that the large icon setting was changed for
 * columns layout.  Large icons are default.
 */
String PREFERENCE_COLUMNS_ICON_SIZE  = "Use Large Icons - Columns"; //$NON-NLS-1$

/**
 * @deprecated	Use PREFERENCE_COLUMNS_ICON_SIZE instead.
 */
String PREFERENCE_FOLDER_ICON_SIZE   = PREFERENCE_COLUMNS_ICON_SIZE;

/**
 * Property name for the large icon setting for list layout.  If the PropertyChangeEvent
 * fired has this property name, it means that the large icon setting was changed for
 * list layout.  Small icons are default.
 */
String PREFERENCE_LIST_ICON_SIZE = "Use Large Icons - List"; //$NON-NLS-1$

/**
 * Property name for the large icon setting for icons only layout.  If the
 * PropertyChangeEvent fired has this property name, it means that the large icon setting
 * was changed for icons only layout.  Large icons are default.
 */
String PREFERENCE_ICONS_ICON_SIZE = "Use Large Icons - Icons"; //$NON-NLS-1$

/**
 * Property name for the large icon setting for details layout.  If the
 * PropertyChangeEvent fired has this property name, it means that the large icon setting
 * was changed for details layout.  Small icons are default.
 */
String PREFERENCE_DETAILS_ICON_SIZE = "Use Large Icons - Details"; //$NON-NLS-1$

/**
 * Property name for the palette font setting.  If the PropertyChangeEvent fired
 * has this property name, it means that the palette font was changed.
 */
String PREFERENCE_FONT = "Palette Font"; //$NON-NLS-1$ 

/**
 * @param listener the PropertyChangeListener to be notified of changes
 * @see java.beans.PropertyChangeSupport#addPropertyChangeListener(
 * java.beans.PropertyChangeListener)
 */
void addPropertyChangeListener(PropertyChangeListener listener);

/**
 * Returns the current auto-collapse setting.
 * <p> 
 * Possible values returned:
 * <ul>
 * 		<li>COLLAPSE_ALWAYS (Always collapse)</li>
 * 		<li>COLLAPSE_AS_NEEDED (Collapse when needed)</li> 
 * 		<li>COLLAPSE_NEVER (Never collapse)</li>
 * </ul>
 * 
 * @return One of the above-mentioned constants
 */
int getAutoCollapseSetting();

/**
 * @return The FontData for the font to be used in the palette.
 */
FontData getFontData();

/**
 * Returns the current layout setting.
 * <p> 
 * Possible values returned:
 * <ul>
 * 		<li>LAYOUT_COLUMNS (columns View)</li>
 * 		<li>LAYOUT_LIST (List View)</li> 
 * 		<li>LAYOUT_ICONS (Icons Only View)</li>
 * 		<li>LAYOUT_DETAILS (Details View)</li>
 * </ul>
 * 
 * @return One of the above-mentioned constants
 */
int getLayoutSetting();

/**
 * Returns the layout modes that are supported.  All four layout modes --
 * LAYOUT_COLUMNS, LAYOUT_LIST, LAYOUT_ICONS, LAYOUT_DETAILS -- are supported by default. 
 * 
 * @return The layout modes that are supported
 * @see #setSupportedLayoutModes(int[])
 */
int[] getSupportedLayoutModes();

/**
 * This is a convenience method.  Instead of getting the supported layout modes and
 * checking to see if a certain layout is supported, you can call this method.
 * 
 * @param layout	LAYOUT_COLUMNS, LAYOUT_LIST, LAYOUT_ICONS, or LAYOUT_DETAILS
 * @return <code>true</code> if the given layout is a supported mode
 */
boolean isSupportedLayoutMode(int layout);

/**
 * @param listener the PropertyChangeListener that should not be notified hereafter
 * @see java.beans.PropertyChangeSupport#removePropertyChangeListener(
 * 														java.beans.PropertyChangeListener)
 */
void removePropertyChangeListener(PropertyChangeListener listener);

/**
 * Sets the auto-collapse setting.
 * <p>
 * Possible values:
 * <ul>
 * 		<li>COLLAPSE_ALWAYS (Always collapse)</li>
 * 		<li>COLLAPSE_AS_NEEDED (Collapse when needed)</li> 
 * 		<li>COLLAPSE_NEVER (Never collapse)</li>
 * </ul>
 * 
 * @param newVal	One of the above-mentioned constants
 */
void setAutoCollapseSetting(int newVal);

/**
 * Sets the FontData for the palette.
 * 
 * @param	data	The FontData for the font to be used in the palette
 */
void setFontData(FontData data);

/**
 * Sets the given setting as the current layout.
 * <p> 
 * Possible values:
 * <ul>
 * 		<li>LAYOUT_COLUMNS (Columns View)</li>
 * 		<li>LAYOUT_LIST (List View)</li> 
 * 		<li>LAYOUT_ICONS (Icons Only View)</li>
 * 		<li>LAYOUT_DETAILS (Details View)</li>
 * </ul>
 * 
 * @param	newVal	One of the above-mentioned constants
 */
void setLayoutSetting(int newVal);

/**
 * Sets the "Use Large Icons" option for the currently active layout.
 * 
 * @param	newVal	<code>true</code> if large icons are to be used with the current layout
 * 					setting
 */
void setCurrentUseLargeIcons(boolean newVal);

/**
 * The client can restrict the modes that the palette supports using this method.  By
 * default, the palette will support all layout modes: LAYOUT_ICONS, LAYOUT_DETAILS,
 * LAYOUT_COLUMNS, LAYOUT_LIST.  Should the client wish to not support all these modes,
 * they can call this method with an array of the desired modes.  This method should be
 * called during set-up as soon as the preferences are created, and not later.
 * <p>
 * If the default layout mode and/or the current layout mode are not in the given array,
 * the first layout mode in the given array will be set to be the default/current layout.
 * </p> <p>
 * NOTE: The given array of layout modes should have at least one, and is recommended to
 * have at least two, of the recognized layout modes.
 * </p>
 * 
 * @param	modes	an array of layout modes desired
 */
void setSupportedLayoutModes(int[] modes);

/**
 * Sets the "Use Large Icons" option for the given layout.
 * <br> 
 * The defaults are as follows:
 * <ul>
 * 	<li>LAYOUT_COLUMNS  - <code>true</code></li>
 * 	<li>LAYOUT_LIST    - <code>false</code></li>
 * 	<li>LAYOUT_ICONS   - <code>true</code></li>
 * 	<li>LAYOUT_DETAILS - <code>false</code></li>
 * </ul>
 * 
 * @param	layout	any of the above-mentioned constants
 * @param	newVal	<code>true</code> if large icons are to be used with the given layout
 */
void setUseLargeIcons(int layout, boolean newVal);

/**
 * Indicated whether large icons should be used with the given layout mode.
 * <br> 
 * The defaults are as follows:
 * <ul>
 * 	<li>LAYOUT_COLUMNS  - <code>true</code></li>
 * 	<li>LAYOUT_LIST    - <code>false</code></li>
 * 	<li>LAYOUT_ICONS   - <code>true</code></li>
 * 	<li>LAYOUT_DETAILS - <code>false</code></li>
 * </ul>
 * 
 * @param	layout	any of the above-mentioned constants
 * @return <code>true</code> if large icons are to be used with the given layout
 */
boolean useLargeIcons(int layout);

/**
 * @return <code>true</code> if large icons are to be used with the currently active
 * layout
 */
boolean useLargeIcons();

}
